Release 10.1A: OpenEdge Development:
Progress 4GL Reference

DEFINE DATASET statement

Defines a static ProDataSet object that is created at compile time, and lets you name the object, identify the temp-table buffers it incorporates, and define the data relations between those buffers.

Syntax

DEFINE [ NEW [ SHARED ] ]        [ PRIVATE | PROTECTED ] DATASET dataset-name        [ NAMESPACE-URI namespace ] [ NAMESPACE-PREFIX prefix ]        [ REFERENCE-ONLY ]        FOR buffer-name [ , buffer-name ] ...        DATA-RELATION [ data-rel-name ] FOR data-rel-spec        [ DATA-RELATION [ data-rel-name ] data-rel-spec ] ...

NEW SHARED DATASET dataset-name

Defines and identifies a ProDataSet object that can be shared by one or more procedures called directly or indirectly by the current procedure. The ProDataSet object remains available to other procedures until the procedure that defined it ends. The called procedures must define the same ProDataSet object name as SHARED. For shared ProDataSet objects, each buffer-name must be the name of a shared buffer.

SHARED DATASET dataset-name

Defines and identifies a ProDataSet object that was initially defined by another procedure as NEW SHARED. For shared ProDataSet objects, each buffer-name must be the name of a shared buffer.

The procedure that initially defines the object determines the name. The procedures that share the object must define the object with the same name.

[ PRIVATE | PROTECTED ] DATASET dataset-name

Defines and identifies a ProDataSet object as a data member for a class, and optionally specifies an access mode for that data member. You must define the temp-tables and buffers of the ProDataSet object with the same access mode as the ProDataSet object. Do not specify an access mode when defining a ProDataSet object for a method within a class.

PRIVATE data members can be accessed only by the defining class. PROTECTED data members can be accessed by the defining class and any of its inheriting classes. The default access mode is PRIVATE.

Note: These options are applicable only when defining a data member for a class in a class definition (.cls) file.

DATASET dataset-name

Identifies the name of the ProDataSet object. You can define the ProDataSet object in a procedure, a method within a class, or an interface.

NAMESPACE-URI namespace

An optional CHARACTER constant that specifies the URI for the namespace of the ProDataSet object.

NAMESPACE-PREFIX prefix

An optional CHARACTER constant that specifies the namespace prefix associated with the NAMESPACE-URI.

REFERENCE-ONLY

Specifies that the procedure defining this ProDataSet object is using the object definition only as a reference to a ProDataSet object that is defined and instantiated in another procedure or class, and specified as a parameter in the invocation of a RUN statement, a method in a class, or a user-defined function, using either the BY-REFERENCE or BIND option. Progress does not instantiate the reference-only object.

Passing a reference-only ProDataSet object parameter to a local routine, using either the BY-REFERENCE or BIND option allows the calling routine and the called routine to access the same object instance (instead of deep-copying the parameter).

Note: If you pass the parameter to a remote procedure, Progress deep-copies the parameter on OUTPUT and the reference-only parameter is bound to that copy.

When you pass a ProDataSet parameter to a local routine using the BY-REFERENCE option, both the calling and called routines access the calling routine’s object instance (and ignore the called routine’s object instance). Since the called routine’s object instance is ignored, you should define the object as a reference-only object. When you define a reference-only ProDataSet object in the called routine and receive it from the calling routine using the BY-REFERENCE option, Progress binds the definition of the object in the called routine to the object instance in the calling routine for the duration of the called routine. You cannot define a reference-only ProDataSet object in the calling routine and pass it to the called routine using the BY-REFERENCE option.

When you pass a ProDataSet parameter to a local routine using the BIND option, you can define a reference-only ProDataSet object in either the calling routine or the called routine as follows:

When you define a reference-only ProDataSet object in the calling routine and pass it to the called routine using the BIND option, Progress binds the calling routine to the object instance in the called routine. The reference-only object definition remains bound to the object instance until the routine containing the reference-only object definition is deleted or terminates. The parameter must be an OUTPUT parameter.
Note: If you also define the ProDataSet object instance in the called routine as a reference-only object, you must bind the object in the called routine before returning to the calling routine.
When you define a reference-only ProDataSet object in the called routine and receive it from the calling routine using the BIND option, Progress binds the called routine to the object instance in the calling routine. The reference-only object definition remains bound to the object instance until the routine containing the reference-only object definition is deleted or terminates. The parameter must be an INPUT or INPUT-OUTPUT parameter.

In either case, you must specify the BIND option for the parameter in both the invocation of a RUN statement, a method in a class, or a user-defined function, and in the DEFINE PARAMETER statement.

Caution: Do not delete the object or routine to which a reference-only ProDataSet object is bound, or you might be left with references to an object that no longer exists.

When you define a ProDataSet object as reference-only, you must also define all member temp-tables as such. A temp-table object defined as reference-only can be a member of a reference-only ProDataSet object or a standard ProDataSet object. However, if you define a reference-only temp-table in a standard ProDataSet object, you cannot use the ProDataSet object until you bind the reference-only temp-table.

FOR buffer-name [ , buffer-name ] ...

Specifies a static buffer for a previously defined temp-table whose scope includes the procedure in which the ProDataSet object was defined.

DATA-RELATION [ data-rel-name ] FOR data-rel-spec

Specifies a data-relation object.

The data-rel-name argument lets you name the data-relation object. You can use this name to obtain the object’s handle at runtime. This argument is optional. The default name is Relationn (where n starts at 1 for each ProDataSet object).

The data-rel-spec argument specifies a pair of parent and child buffers for the data-relation object using the following syntax:

parent-buffer-name, child-buffer-name [ field-mapping-phrase ] [ REPOSITION ] [ NESTED ]

parent-buffer-name

The parent buffer in the data-relation object.

child-buffer-name

The child buffer in the data-relation object.

field-mapping-phrase

Specifies the fields in the relation using the following syntax:

RELATION-FIELDS (parent-field1, child-field1      [, parent-fieldn, child-fieldn ] ...)

The first field in the pair is from the parent buffer, the second field is from the child buffer. When filling the ProDataSet object, Progress retrieves data for the child buffer based on an equality match between all pairs of fields unless the Data-Relation is deactivated or there is an explicit query definition for the data source of the child buffer.

You can define a query for the data source of the child buffer, or supply custom logic in response to FILL events that take over complete responsibility for filling one level of the ProDataSet object. In these cases, the field-mapping-phrase is not used.

When navigating the ProDataSet object, Progress filters the data in the child buffer to include only children of the current parent.

REPOSITION

Specifies the relation mode as REPOSITION. The relation mode is SELECTION, by default.

When the relation mode is SELECTION, the ProDataSet object fills the child temp-table of the relation with all records related to the current parent. When the relation mode is REPOSITION, the relation is effectively ignored during a FILL, and the child of the relation is treated as if it were a top-level buffer.

When navigating a filled ProDataSet object with a SELECTION relation, related data is filtered as it is browsed. This means the child query of the relation is filtered to make available only children of the current parent, and the query is re-opened each time the parent table is repositioned. When navigating a filled ProDataSet object with a REPOSITION relation, the child table query is always set to match all the rows in the child table, and is not re-opened when the parent changes. Only the buffer for the child is repositioned to the matching child for the current parent.

NESTED

Specifies that child rows of a ProDataSet buffer are nested within their parent rows when writing the XML representation of data or schema. This also causes the XML Schema definitions for the related temp-tables to be nested.

Notes

You cannot define a SHARED or NEW SHARED ProDataSet object in a class definition (.cls) file. If you do, Progress generates a compilation error.
You cannot define a ProDataSet object within an internal procedure, a method in a class, or a user-define function.

See also

Buffer object handle, CREATE DATASET statement, Data-relation object handle, DEFINE TEMP-TABLE statement, GET-TOP-BUFFER( ) method, NUM-REFERENCES attribute, ProDataSet object handle